GO Vault

README

5 min read

File Organization System

A comprehensive, intelligent file organization system that uses multi-level logic, AI integration, and adaptive learning to automatically organize files based on content, context, and user behavior.

🚀 Features

Core Capabilities

  • Multi-Format Content Analysis: PDF, HTML, Audio, Video, Documents
  • Intelligent Routing: Source-first, Theme-first, and Project-first strategies
  • Confidence Scoring: Multi-probe analysis with weighted confidence assessment
  • Focus-Aware Context: Temporal learning of user focus patterns
  • LLM Integration: Ollama (local) and OpenAI (cloud) for complex cases
  • Adaptive Learning: System improves based on user feedback and corrections

Advanced Features

  • Multimodal Intelligence: Image, audio, and video content analysis
  • Vector Search: Semantic similarity and content-based retrieval
  • Cloud Integration: Selective backup and cross-device synchronization
  • External Tool Integration: Research databases, note-taking systems, productivity tools
  • Directory Opus Integration: Windows file manager integration

🏗️ Architecture

The system is built on 10 levels of logic:

  1. Content Recognition Layer: Universal content extraction and normalization
  2. Confidence Assessment: Multi-probe analysis and weighted scoring
  3. Intelligent Routing: Multi-strategy path construction and placement
  4. Focus-Aware Context: Temporal learning and user behavior modeling
  5. Execution & Safety: Decision engine with safety protocols
  6. User Interface & Control: Excel control plane and Streamlit dashboard
  7. Data Integration & Learning: Database architecture and learning mechanisms
  8. LLM Integration: Progressive enhancement pipeline
  9. Integration & Extensibility: External tool integration
  10. Advanced Features: Multimodal intelligence and cloud integration

🛠️ Installation

Prerequisites

  • Python 3.8+
  • PostgreSQL (for vector search capabilities)
  • Ollama (for local LLM processing)
  • Windows (for Directory Opus integration)

Setup

# Clone the repository
git clone <repository-url>
cd file-organization-system
 
# Install dependencies
pip install -r requirements.txt
 
# Set up environment variables
cp .env.example .env
# Edit .env with your configuration
 
# Initialize database
python scripts/init_db.py
 
# Start the system
python main.py

📁 Project Structure

file-organization-system/
├── core/                    # Core system logic
│   ├── content_analysis/   # Content extraction and analysis
│   ├── confidence/         # Confidence scoring system
│   ├── routing/            # File routing logic
│   ├── focus_model/        # User focus tracking
│   └── execution/          # Decision execution engine
├── llm/                    # LLM integration
│   ├── ollama/            # Local LLM processing
│   └── openai/            # Cloud LLM processing
├── ui/                     # User interfaces
│   ├── excel/             # Excel control plane
│   └── streamlit/         # Web dashboard
├── integration/            # External tool integration
│   ├── directory_opus/    # Windows file manager
│   ├── research_tools/    # Academic databases
│   └── note_systems/      # Note-taking applications
├── database/               # Database models and queries
├── utils/                  # Utility functions
└── tests/                  # Test suite

🔧 Configuration

Excel Control Plane

The system can be controlled through Excel spreadsheets:

  • Dashboard: System metrics and control buttons
  • Catalog: File inventory with metadata and decisions
  • Notes: Timestamped journal and context linking
  • Config: System parameters and thresholds
  • Structure Detector: Pattern definitions and rules

Streamlit Dashboard

Web-based interface for:

  • Real-time file processing
  • Visual confidence indicators
  • Drag-and-drop file handling
  • Interactive configuration

📊 Usage

Basic File Organization

  1. Scan Folder: Point the system to a folder to analyze
  2. Review Decisions: Check confidence scores and suggested destinations
  3. Apply Actions: Automatically organize files based on confidence
  4. Provide Feedback: Correct any mistakes to improve the system

Advanced Features

  • Multi-Placement: Files can be linked to multiple destinations
  • Series Detection: Automatic grouping of related files
  • Focus Learning: System adapts to your current work patterns
  • Cloud Sync: Intelligent backup of important files

🤖 AI Integration

Local Processing (Ollama)

  • Fast, privacy-preserving analysis
  • Handles most file organization decisions
  • No internet connection required

Cloud Processing (OpenAI)

  • Advanced analysis for complex cases
  • Escalation when local processing is insufficient
  • Configurable usage limits and costs

🔒 Safety Features

  • Never Delete: All operations are moves or links
  • Atomic Operations: All-or-nothing file operations
  • Undo System: Complete operation history with rollback
  • Quarantine: Uncertain files are held for review
  • Collision Handling: Intelligent conflict resolution

📈 Learning & Adaptation

The system continuously improves through:

  • User Feedback: Learning from corrections and overrides
  • Pattern Recognition: Discovering organizational patterns
  • Confidence Calibration: Adjusting thresholds based on performance
  • Focus Evolution: Adapting to changing user priorities

🌐 Integration

Windows Integration

  • NTFS metadata writing
  • Directory Opus integration
  • Windows shell integration

External Tools

  • Research: Zotero, Mendeley, Papers
  • Notes: Obsidian, Roam Research, Notion
  • Productivity: Todoist, Trello, Asana

📝 Development

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Testing

# Run all tests
python -m pytest
 
# Run specific test categories
python -m pytest tests/core/
python -m pytest tests/llm/

📄 License

This project is licensed under the MIT License - see the license file for details.

🙏 Acknowledgments

  • Built with Streamlit for the web interface
  • Uses Ollama for local AI processing
  • Integrates with OpenAI for advanced analysis
  • Designed for Windows Directory Opus integration

📞 Support

For questions, issues, or contributions:

  • Open an issue on GitHub
  • Check the documentation
  • Review the example configurations

Ring 2 — Canonical Grounding

Ring 3 — Framework Connections

Note: This is a sophisticated system designed for power users who want intelligent, automated file organization. The system learns from your behavior and adapts to your organizational preferences over time.

Canonical Hub: CANONICAL_INDEX

Graph View